FishMarket 1.0/FishMarket v1.0.iso/fishies/076-100/disk_081/icon/amiga.doc

Text File | 1992-05-06 | 22KB | 576 lines

                      Version 6.0 of Icon for the Amiga

                               Scott Ballantyne




    1. Introduction

       Version 6 of Icon for the Amiga should run on any Amiga with
    at least 512k of memory and running Kickstart Version 1.2
    Due to the intense memory requirements of Icon, more memory is
    recommended, however, with few exceptions, you should be able to
    handle most programming tasks on a 512k box.


       The Amiga implementation of Icon is the work of Scott Ballantyne
    and Gary Sarf, and may be freely distributed on the usual 'use
    at your own risk' basis.  It is based on the public domain version
    of Icon from the University of Arizona.

       The University of Arizona has released an upgraded version of
    Icon (V6.3), which fixes a few bugs in Version 6.0.  We hope to
    make this available on the Amiga in a few months.  We will also
    be releasing the source code for Amiga Icon at that time.
    Meanwhile, 6.0 is very usable as it is.  Version 6.3 for the Amiga
    will also be using the arp.library, and so should be somewhat smaller.

       If you encounter any bugs or problems I would like to hear
    about them:

    BIX: SDB
    CIS: 70066,603

    And elsewhere...

    2. Documentation

       The basic reference for the Icon programming language is the
    book

         The Icon Programming Language, Ralph E. Griswold and Madge
         T. Griswold, Prentice-Hall, Inc., Englewood Cliffs, New Jer-
         sey, 1983. 313 pages. ISBN 0-13-449777-5. $25.95.

    This book is available in many college bookstores or can be
    ordered through any bookstore that handles special orders or by
    telephone directly from Prentice-Hall: [phone].

       A brief overview of Icon is contained in technical report TR
    83-3 [1] (overview.doc on the distribution diskette). Features
    that have been added to Icon since the book was written are
    described in TR 86-10b [2] (version6.doc on the distribution
    diskette).  These technical reports, together with this document
    (Amiga.doc on this diskette), provide enough information to write
    simple Icon programs, but persons who are going to use Icon seri-
    ously will need the book.


    3. Installing Amiga Icon

       There are five executable binary files needed to run Icon:

            Icont   command processor
            Itran   translator
            Ilink   linker
            Iconx   run-time system
        ixhdr   start-up code

       Icont should be located on a place in your Path specification, while
    the remaining files may be placed wherever you like, however, you
    need to tell Icon where they are by making the following Assigns:

    Assign ICONX:    location of Iconx
    Assign ICONT:    location of Icont
    Assign ILINK:   location of Ilink
    Assign ITRAN:    location of Itran
    Assign HEAD:    location of ixhdr

    If you start to get requesters which say, for example, "Please Insert
    Volume ICONX: in any drive", it is because you forgot to make these
    Assigns.  The easiest way to do this is to use a batchfile, or the
    startup-sequence file if you boot to an Icon disk.

    You will also need the Set program, which is included on this diskette,
    and is the work of Thomas Rokicki of Radical Eye Software.  The MANX Set
    may also be used, but the two versions of Set (the Rokicki Set and the
    MANX set) should not be mixed.  If you are intending to use floating
    point math, then you will also need the mathieeedoubbas.library (as
    supplied on 1.2 Workbench disks) in the LIBS: directory.


    4. Running Amiga Icon - Basic Information

       Files containing Icon programs must have the extension .icn.
    Such files should be plain text files (without line numbers or
    other extraneous information).  The command processor icont runs
    itran and ilink to produce an ``icode'' file that can be executed
    by iconx.  For example, an Icon program in the file prog.icn is
    translated and linked by

            1> icont prog.icn

    The result is an icode file with the name prog (with the exten-
    sion removed).  This file can be run by simply typing it's name,
    as though it were a binary machine code file, or by providing it
    as an argument to the icon runtime system as:

            1> prog
    or
        1> iconx prog

    Alternatively, icont can be instructed to execute the program
    after linking and translating by appending a -x to the command
    line, as in

            icont prog.icn -x

    In this case the file prog also is left and can be run subse-
    quently simply by typing it's name at the CLI prompt.

       If you find you are having difficulty due to memory constraints,
    there are various environment variables used by Icon which you may
    use to ''fine-tune'' your version. Section 6 has more information
    about other aspects of running Icon.


    5. Testing the Installation

       There are a few programs on the distribution diskette that may
    be used for testing the installation and getting a feel for run-
    ning Icon:

    hello.icn   This program prints the Icon version number, time,
                and date. Run this test as

                        1> icont hello.icn
                        1> hello

                Note that this can be done in one step with

                        1> icont hello.icn -x


    cross.icn   This program prints all the ways that two words
                intersect in a common character. The file cross.dat
                contains typical data. Run this test as

                        1> icont cross.icn
            1> cross <cross.dat



    meander.icn This program prints the ``meandering strings'' that
                contain all subsequences of a specified length from a
                given set of characters. Run this test as

                        1> icont meander.icn
            1> meander <meander.dat


    roman.icn   This program converts Arabic numerals to Roman
                numerals. Run this test as

                        1> icont roman.icn -x

                and provide some Arabic numbers from your console.  Hit
        CNTRL-\ when you want to terminate.

    wordcnt.icn This program tabulates the number of occurrences of
                each word from the input file. Run this test as

                        1> icont wordcnt.icn
            1> wordcnt <file

                where file contains some text of interest. Caution:
                the tabulation is kept in memory; do not try to pro-
                cess a large file - unless you have a lot of memory!

    If these tests work, your installation is probably correct and
    you should have a running version of Icon.  If you want to save
    the output from any of these programs, you may redirect the output
    as well, for example:

        1> wordcnt <file >outfile

    If there are other examples included, have fun with them!

    6. More on Running Icon

       For simple applications, the instructions for running Icon
    given in Section 4 may be adequate. The icont command processor
    supports a variety of options that may be useful in special
    situations.  There also are several aspects of execution that can
    be controlled with environment variables.  These are listed here.
    Persons who are new to Icon may wish to skip this section on the
    first reading but come back to it if they find the need for more
    control over the translation and execution of Icon programs.

    6.1 Arguments

       Arguments can be passed to the Icon program by appending them
    to the command line.  Such arguments are passed to the main pro-
    cedure as a list of strings.  For example,

            1> prog text.dat log.dat

    runs the icode file prog, passing its main procedure a list of
    two strings, "text.dat" and "log.dat".  The program also can be
    translated, linked, and run with these arguments with a single
    command line by putting the arguments after the -x:

            1> icont prog.icn -x text.dat log.dat

    These arguments might be the names of files that prog1.icn reads
    from and writes to. The main procedure might begin as follows:

            procedure main(a)
               in := open(a[1]) | stop("cannot open input file")
               out := open(a[2],"w") | stop("cannot open output file")
                           .
                           .
                           .

    See also the information about the processing of command-line
    arguments given in Section 6.4.

    6.2 The Command Processor

       The command processor icont can accept several input files at
    one time.  When several files are given, they are translated and
    combined into a single icode file whose name is derived from the
    name of the first file.  For example,

            icont prog1.icn prog2.icn

    translates and links the files prog1.icn and prog2.icn and pro-
    duces one icode file, prog1.

       A name other than the default one for the icode file produced
    by the Icon linker can be specified by using the -o option, fol-
    lowed by the desired name. For example,

            icont -o probe prog.icn

    produces the icode file named probe rather than prog.

       If the -c option is given to icont, only translation is per-
    formed and intermediate ``ucode'' files with the extensions .u1
    and .u2 are kept.  For example,

            icont -c prog1.icn

    leaves prog1.u1 and prog1.u2, instead of linking them to produce
    prog1. (The ucode files are deleted unless the -c option is
    used.) These ucode files can be used in a subsequent icont com-
    mand by using the .u1 name. This avoids having to translate the
    .icn file again. For example,

            icont prog2.icn prog1.u1

    translates prog2.icn and links the result with the ucode files
    from a previous translation of prog1.icn. Note that only the .u1
    name is given. Ucode files also can be added to a program when it
    is linked by using the link declaration in an Icon source program
    as described in [2].

       It is worth noting that icont only controls the execution of
    the other components of the Icon system. For example,

            icont prog.icn -x

    is equivalent to

            itran prog.icn
            ilink prog.u1
            iconx prog

    The Amiga version of Icont has a -v option, which will display the
    command lines it is executing.  This can be useful if you are
    curious about exactly what information Icont is sending the various
    subsystems.

       Icon source programs may be read from standard input.  The
    argument - signifies the use of standard input as a source file.
    In this case, the ucode files are named stdin.u1 and stdin.u2 and
    the icode file is named stdin.  You indicate that you are finished
    with the text entry by typing CNTRL-\ (the Amiga standard EOF indicator).

       The informative messages from the translator and linker can be
    suppressed by using the -s option.  Normally, both informative
    messages and error messages are sent to standard error output.

       The -t option causes &trace to have an initial value of -1
    when the program is executed.  Normally, &trace has an initial
    value of 0.

       The option -u causes warning messages to be issued for unde-
    clared identifiers in the program.  The warnings are issued dur-
    ing the linking phase.

       Icon has several tables related to the translation and linking
    of programs.  These tables are large enough for most programs,
    but translation or linking is terminated with an error message,
    indicating the offending table, if there is not enough room.  If
    this happens, larger table sizes can be specified by using the -S
    option. This option has the form -S[cfgilrstCL]n, where the
    letter following the S specifies the table and n is the number of
    storage units to allocate for the table.


         c  constant table          100
         f  field table             100
         g  global symbol table     200
         i  identifier table        500
         l  local symbol table      100
         r  record table            100
         s  string space         15,000
         t  tree space           15,000
         C  code buffer          20,000
         L  labels                  500

    The units depend on the table involved, but the default values
    can be used as guides for appropriate settings of -S options
    without knowing the units.  For example,

            icont -Sc200 -Sg600 prog.icn

    translates and links prog.icn with twice the constant table space
    and three times the global symbol table space that ordinarily
    would be provided.

    6.3 Environment Variables

       When an Icon program is executed, several environment vari-
    ables are examined to determine certain execution parameters.
    You establish the values of environment variables by using Set,
    which should be included with the Amiga Icon distribution
    package.  Syntax is

    set STRING=VALUE

   VALUE can be anything, numeric or string data, that is required
   by Icon.  Generally, the Icon environment variables require numbers.
   When setting a numeric environment variable do not include commas
   or other formatting characters - digits only.

   If you type Set, by itself, with no arguments, then it will display
   a list of all currently defined environment variables, along with their
   values.

   Finally, to remove an environment variable from memory, just type

        Set STRING=

   With nothing following the '=' sign, and this variable will be removed.

       Environment variables are particularly useful in adjusting
    Icon's storage requirements. This may be necessary if your com-
    puter does not have enough memory to run Icon as configured or for programs
    that have unusual demands for a particular kind of data.  Partic-
    ular care should be taken when changing default sizes: unreason-
    able values may cause Icon to malfunction.

       The variables that affect the execution of Icon are:

       TRACE initializes the value of &trace.  If this variable has a
    value, it overrides the translation-time -t option.

       NBUFS determines the number of i/o buffers used for files.
    When a file is opened, it is assigned an i/o buffer if one is
    available and the file is not the console.  If no buffer is
    available, the file is not buffered.  &input, &output, and
    &errout are buffered if buffers are available.  The defualt for
    the Amiga implementation is 10.

       If NOERRBUF is set, &errout is not buffered.

       STRSIZE determines the initial size of the string space, in
    bytes.  The string space grows if necessary, but it never
    shrinks.  For the Amiga implementation of Icon, the default
    value of STRSIZE is 51,200. If the amount of memory available for
    running the Icon is small, the initial size of the string space
    can be set to a smaller value, such as 10,000.

       HEAPSIZE determines the initial size of the allocated block
    region, in bytes.  The heap grows if necessary, but it never
    shrinks.  The default value of HEAPSIZE is 51,200.  If the amount
    of memory available for running Icon is small, the initial size of
    the allocated block region can be set to a smaller value, such as 10,000.

       COEXPSIZE determines the size, in words, of each co-expression
    block.  The default value of COEXPSIZE is 2,000.


       MSTKSIZE determines the size, in words, of the main inter-
    preter stack. The default value of MSTKSIZE is 10,000.
    The size of the main interpreter stack can be set to a smaller
    value, such as 5,000. If the main interpreter stack is not large
    enough, excessive recursion may lead to program termination with
    a run-time error message.

       STATSIZE determines the size, in bytes, of the static region
    in which co-expression blocks are allocated. The default value of
    STATSIZE is 20,480.
    If the amount of memory available for running Iconis small,
    the size of the static region can be set to a small value, such
    as 100, provided that co-expressions are not used.

       STATINCR determines the size of the increment used when the
    static region is expanded.  The default increment is one-fourth
    of the initial size of the static region.

    Icon on the Amiga allocates all it's memory from one big
    heap.  Initially, Icon will attempt to grab the largest section
    of contiguos memory it can find.  If you wish to limit the amount
    of memory Icon will ask for, then you can set the the maximum amount
    of memory Icon will ask for with the MAXMEM environment variable.
    This variable should specify a value in Kbytes, thus MAXMEM=300
    will limit the amount of memory Icon will request to 300k bytes.
    Note that you may not get all the memory you ask for - Icon will
    attempt to get the amount of memory you asked for, but if it is
    not available, will ask for less.  You will not get an out of memory
    error if this occurs.  Out of memory errors will occur only when
    an Icon program needs more memory than Icon has available, and this
    is determined as the program runs its course, not during the icon
    system initialization.

    You can use the environment variable UFILES to establish where
    icont will place the temporary .u? files.  By setting UFILES=RAM:,
    these will be placed in the ram disk, greatly speeding up the linking
    and translating phases of the process.

       Amiga Icon supports all the features of Version 6 of Icon,
    with the following exceptions and additions:


         o  Pipes are not supported. A file cannot be opened with the
            ``p'' option.


     o  The PATH environment variable is not used on the Amiga, instead,
        the CLI path is searched, as set by the Path command.

         o  The IPATH environment string used by the Icon linker, is
            supported as described in [2].  The separator between
            paths is the bang ('!'). The current directory is always
            searched. You should specify a ':' in volume names,
        but you should not add a trailing '/' to path names.
        For example:

            set IPATH=df1:!df1:Iconstuff!df1:icontstuff/bookstuff

        will cause the linker to examine the current directory for
        linkable files, then the root directory of df1:, then Df1:Iconstuff,
        then df1:iconstuff/bookstuff.

         o  All of the AmigaDOS logical devices can be used as files,
            this provides a simple means to output to a window, by opening
        a CON: or RAW: window.

         o  Trace output is sent to STDERR.

    The following functions have been added to Icon only for the Amiga version,
    and should not be expected to be found on other versions:


    o Translate(string) -- returns translated string, try:
        Write(Translate("Hello big boy"))

    o Narrate(string, rate, pitch, mode, sex, volume, sampfreq, side)
        You can simply do Narrate(Translate(string)) if you want
        to accept the defaults, or you can set specific parameters:

        rate - rate of speaking -- 40 to 400, default is 150
        pitch - pitch of voice -- 65 to 320. default is 110
        mode - may be "natural" or "robotic", or you may use 0 or 1.
            default is natural (0).
        sex - may be "male" or "female", or you may use 0 or 1
            default is male (0)
        volume - loudness of voice -- 0 (silence) to 64, default is 64
        sampref - sample frequency. 5000 to 28000, default is 22200
        side - may be "both", "right" or "left", to set the speaker from
            which the voice will come, default is "both".

        NOTE:  You will have to use MAXMEM to limit the amount of
        memory initially grabbed by icon, or there will not be
        enough room in memory for the translator and narrator when
        you call these functions!


    o Delay(timeout) - wait timeout ticks, 50 per second, returns #seconds
               Delayed, defaults to 1 second.  You should use this
               if you want a delay, instead of busy waiting.

    o DeleteFile(file) -- Delete a file.
    o Rename(old, new) -- Rename files
    o SetComment(file, string) -- Set a comment for file

    All of these functions use the Icon conventions as much as possible.

    The following functions are also extensions to Icon, but are common
    enough across implementations that you can somewhat depend on them:

MATH:
    exp(x)
    log(x)
    log10(x)
    sqrt(x)
TRIG:
    sin(x)
    cos(x)
    tan(x)
    acos(x)
    asin(x)
    atan(x)
    atan2(x, y)
    dtor(x)        # Convert degrees to radians
    rtod(x)        # Radians to degrees
FILES:
    seek(file, offset, start) - aka C's fseek.
GETENV:
    getenv(s) - return contents of environment variable s

    6.4  Further details about running Icon programs.

    Icon does not actually produce machine code executable files.
    What actually happens is that the linker (Ilink) writes an executable
    file header (the program ixhdr, located in assigned directory HEAD:)
    which then loads and runs Iconx (the run time system) passing itself
    as an argument.  This appears complex, but is actually the way Icon
    is handled on most systems - Icon compilers do not actually increase
    execution speed by very much, but they do increase program size a
    considerble amount.

    You may run Icon programs without taking advantage of this feature,
    by simply passing the icon program name to Iconx.  Here are some examples:

    1> prog
    can also be run as
    1> Iconx prog

    1> prog arg1 arg2 arg3
    can also be run as
    1> Iconx prog arg1 arg2 arg3

    1> prog <infile >outfile arg1 arg2 arg3
    can also be run as
    1> Iconx <infile >outfile prog arg1 arg2 arg3

    (Note that order of the arguments in this last one!).

    Of course, in this case, Iconx must be in your search path, and the icon
    program must have it's full name specified - the CLI path will not be
    searched.

    Icon programs may be interrupted by using CNTRL-C.  However, the Icon
    system will only check for the CNTRL-C when it is doing I/O, so if you
    are stuck in an non I/O bound loop, well, it is time to reboot.
________________________________________________

    1.   R. E. Griswold, An Overview of the Icon Programming
         Language, The Univ. of Arizona Tech. Rep. 83-3c, 1983,
         Revised 1986.

    2.   R. E. Griswold, W. H. Mitchell and J. O'Bagy, Version 6 of
         Icon, The Univ. of Arizona Tech. Rep. 86-10b, 1986.